home *** CD-ROM | disk | FTP | other *** search
- .TOPIC:
- Customizing VBBS
-
- VBBS 6.12 Documentation -- 7-1
-
- ╔════════════════════════════════════════════════════════════════╗
- ║ CHAPTER SEVEN CUSTOMIZING VBBS ║
- ╚════════════════════════════════════════════════════════════════╝
-
- The configurability of VBBS can not be overstated.
-
- Because of the way VBBS is structured, it's possible to
- configure the program to look and feel like some other BBS soft-
- ware; you can borrow features from several different BBS soft-
- wares to create your own design. You might just take a vacation
- from reality one night and decide to make VBBS look just like
- GEnie or some other CIS. Aside from the obvious limitations on
- actual storage space, you could accomplish the "look-alike" to
- the point where a user could not tell the difference! By using
- scripts (and the source code, if you've registered for it), you
- can do many things that simply aren't possible with other BBS
- softwares.
- Unlike source code, which normally contains strict rules
- on code segment distribution (VBBS included), VSCRIPT-based ap-
- lications, function blocks, and menus may be distributed freely
- in full, or even in entire configuration sets.
-
-
- Menus, Function Blocks, Scripts, and Mods
- ═════════════════════════════════════════
-
- Customization and modification of VBBS comes in several
- forms: changing the menus to suit your personal tastes and set-
- up, rearranging function-block commands, installing scripts for
- special applications, and even modifying the source code (if
- you've registered at the source level).
- Menus and function blocks are closely interrelated, so
- if you find yourself flipping back and forth between the sec-
- tions on the two, don't worry; it's normal.
- For the remainder of this manual, the term "script" will
- apply exclusively to programs utilizing the VSCRIPT script lan-
- guage; the term "mod" will refer exclusively to modifications
- made at the source-code level. It should be pointed out here
- that you do not need to register VBBS to write scripts or ex-
- change scripts with other sysops via VirtualNET; registration
- and an additional fee ARE, however, required to obtain the VBBS
- source code.
- There are other good reasons to register VBBS; we'll get
- to those presently.
-
-
- "Heart-Code ANSI"
- ═════════════════
-
- If you've read this far, you've run across the term
- "heart-code ANSI" a time or two. Since customization often in-
- volves changing colors and menus and adding system taglines,
- this is probably a good place to explain what "heart-code ANSI"
- is.
-
- VBBS 6.12 Documentation -- 7-2
-
-
- If you've ever used the DOS "type" command to look at a
- file you've created using TheDraw or some other ANSI drawing
- program, you know it consists mainly of "garbage" resembling
- Chinese.
-
- This is the ANSI (American National Standards Institute) code
- for introducing color changes into text files so that the colors
- will show up onscreen; in order to display these color changes,
- you need to have the statement
-
- DEVICE=ANSI.SYS
-
- somewhere in your CONFIG.SYS file (remember, though, about the
- ANSI bomb -- see "First-Time Startup" for details on alternate
- ANSI drivers).
- A while back, a good number of BBS programs began
- using a method of color changing called "heart-code ANSI",
- in which color changes were represented by a heart character
- followed by an alphanumeric character. The heart-code system
- has the benefit of taking only two bytes to accomplish what
- takes 4-6 bytes in "raw" ANSI, thereby reducing the size of
- network transfers, especially where large numbers of color
- changes are involved.
- In an effort to maintain compatibility other bulletin
- board networks, VBBS was designed to handle heart-code
- ANSI. The heart-code colorization system has become the stan-
- dard for these BBS softwares.
- When you're starting out with heart-code ANSI, it's a
- good idea to go into the VBBS FSE and press [Ctrl-P][?], and
- look at the color combinations that appear at the bottom of
- the screen. The same set of color combinations can be seen
- when you go into your [D]efaults setup and start changing
- your screen display colors; you might consider printing out
- that screen using [Shift-Print Screen].
-
- --> IMPORTANT NOTE: If you print-screen the default-menu
- color change information, be aware that
- all the codes are "off" by one; for exam-
- ple, the screen code for gray on black is
- 1, but the heart-code for gray on black
- is 0 (zero). Likewise, the bright-red on
- black is screen code 7, but heart-code 6.
-
- ╔═╗ Using heart-code ANSI takes some getting used to, but
- ╚═╝ with practice, it's not terribly more difficult than
- the "raw" ANSI produced by TheDraw or other ANSI draw
- programs. Heart-code ANSI is best for menus, taglines,
- and other features that have patterned or infrequent
- color changes.
-
- VBBS 6.12 Documentation -- 7-3
-
-
- The easiest way to produce a heart-code menu or tagline
- is to first use an ANSI drawing program to make the menu/tag-
- line, then save it as a straight ASCII text file. Then, pull
- it into the VBBS FSE and use [Ctrl-P] codes to change the co-
- lors (see Appendix C for details).
- To introduce a heart-code color change into an ASCII
- text file, turn Num Lock ON; while holding down the [Alt] key,
- type in either "3" or "259" (whichever works) FROM THE NUMERIC
- KEYPAD. A heart character should appear on your screen. The
- second keystroke should be a number from 0-9 or a letter from
- A-Z, depending on what color you want to produce.
-
-
- Customizing Menus
- ═════════════════
-
- The VBBS archive includes a default set of function blocks
- (see below) and their accompanying menus. After running the de-
- faults for a while, however, most sysops want to customize their
- menus to more accurately reflect their personal tastes and give
- their BBS a distinctive look.
- Default VBBS has four different types of menu files:
-
- .MNU files (the default)
- .ANS and .ASC files
- .PDM files
-
- We'll take a moment to explain each one in detail (there is one
- more menufile type if your BBS is set up to use the R.I.P.
- (Remote Imaging Protocol).
-
- On startup, VBBS looks for menu files with the .MNU ex-
- tension. The .MNU files included with VBBS are done in heart-
- code ANSI, and serve "double duty". If the user's video display
- will support ANSI graphics, the color changes will be included,
- but if it won't (user's defaults set to ASCII), VBBS will strip
- out the color changes for display to that user. The main bene-
- fit of this system is that by using the heart-code .MNU files,
- only one set of menu files is needed for both ANSI and ASCII
- users. Another point in favor of the .MNU files is that they
- seem to display a little bit faster -- this is probably due to
- the fact that it takes only two bytes to make a color change.
-
- The second set of menu formats -- .ANS and .ASC files --
- is what VBBS will look for if it doesn't find .MNU files. The
- .ANS format is "raw" ANSI, such as that produced by TheDraw;
- an .ASC extension represents an ASCII (text) menu. The advan-
- tages to having these files in lieu of .MNU files is that they
-
- VBBS 6.12 Documentation -- 7-4
-
-
- 1) are a little bit quicker to produce, i.e., you draw a
- menu directly in ANSI, save it twice (in .ANS format
- and in .ASC format), and you're done.
- 2) are easier to make, especially if you have very com-
- plex menus and color changes; the heart-code system
- can be a little daunting if your menus are ornate.
-
- The downside of this method is that you must have two copies of
- each menu, one for ANSI users and one for ASCII users; if a user
- with ASCII defaults gets an .ANS menu, he/she will receive gar-
- bage characters (as shown above) and probably won't call back.
-
- The final set of files are VBBS' "pull-down" menus, which
- have a .PDM extension. These are for users who have selected
- "Enhanced ANSI" as their screen display default. These are ac-
- tually ASCII text files that VBBS colorizes as part of the de-
- fault color selection. A user may opt to use .PDMs at any sys-
- tem prompt by pressing the [Esc] key -- and you should try it
- to see how they work. The default FILES.PDM file is shown
- below:
-
- Directory
- C Change Directory [C]
- L List Files [L]
- S Search All Dirs [S]
- N New Files List [N]
- F Find Description [F]
- Transfer
- D Download Files [D]
- U Upload Files [U]
- B Batch Functions [B]
- R Review Files [R]
- Y Your Stats [Y]
- Other
- J New File Scandate [J]
- P Popular Downloads [P]
- M Download Master List [M]
- Q Quit to Main Menu [Q]
- G Log Off [G]
-
- These files are preconfigured, but easily changed using any text
- editor. They don't need to be changed, though, unless you re-
- group or add commands within the function blocks. But --
-
- --> IMPORTANT NOTE: Any changes you make in your .MNU or
- .ANS/.ASC menus should also be made in
- your .PDM files.
-
-
- VBBS 6.12 Documentation -- 7-5
-
-
-
- Creating your own .MNU menus is simple enough: after
- making backups of the original menu files (just in case), use
- your favorite drawing program (or even a text editor capable of
- handling "extended ASCII" characters, although this is a LOT
- more work) to make an ASCII menu file. To add the color
- changes you want, pull the file into the VBBS FSE and use
- heart codes to add color (as described earlier).
-
- ╔═╗ Menus are a great means of customizing your BBS. They're
- ╚═╝ also the primary method by which a user interacts with
- your BBS, so you want to design menus that are as func-
- tional as possible. Please note that complete script/
- function block/menu/pdm packages emulating the look and
- feel of several other bbs softwares have been developed.
- The most notable of these is MVMEN by David Bell with
- emulations of WWIV, Remote Access, WildCat, Renegade, and
- others, in addition to multi-language VBBS modules.
-
-
- Function Blocks
- ═══════════════
-
- At the heart of VBBS' command structure is the FUNCTION
- BLOCK, which is in turn represented by a menu. A function block
- is an easy-to-modify ASCII file which allows the sysop to define
- every single function of any menu -- what each key does, whether
- it is calling an internal function, an external VSCRIPT, external
- .EXE file (shrinking or not shrinking VBBS out of memory as de-
- sired), or calling another function block.
- Creating and editing function blocks may be done with any
- ASCII text editor; the resulting files should be placed in the
- VBBS \V or \VSCRIPT directory you have set up in VCONFIG.
-
- For example, for your FILES.FB, the first line of the function
- block might now read FILE1. This would instruct VBBS to display
- a menu file called FILE1.MNU, FILE1.ANS, FILE1.ASC, or FILE1.PDM
- (depending on which menuing scheme you're using and the user's
- default display setting). Similarly, your START.FB might call
- up the MAIN.xxx menu file, while your SYSOP.FB might call up the
- SYSOP1.xxx menu file.
- The second line holds the letter designators of any topic
- areas that "go with" the function block. For example, if you
-
- VBBS 6.12 Documentation -- 7-6
-
- have message topic areas A, B, C, and D, the second line of your
- START.FB should read
-
- ABCD
-
- Otherwise, your users would only see ONE topic area; the "A"
- topic that came preconfigured as a default. Many new sysops for-
- get to add these other topic designators in; it's not difficult
- to overlook this, even though it IS crucial.
-
- Each subsequent line of a function block enables a "hot-
- key" to perform a particular command or function. Lines in the
- "body" of a function block MUST follow this particular format
- and appear in strict columns:
-
- k xxx y cccccccccccc
-
- An explanation is given below.
-
- Part Column(s) Explanation
- ───── ───────── ────────────────────────────────────────────
- k 1 The letter or symbol serving as the hot-key
- xxx 3-5 The minimum SL needed to access the function
- (must be three digits, like "050" or "007")
- y 7 The command type (a digit 0-5; more on that
- below)
- cccccc 9+ The name of the routine/script/.EXE command
- line, etc.; this section is of variable
- length, depending on what you're trying to
- do.
-
- The "y" in the command line represents a digit from 0
- through 5 that tells VBBS how to execute the command, according
- to the following list:
-
- Digit Command-type Description
- ───── ───────────────────────────────────────────────────────
- 0 Null (no operation)
- 1 Internal command (like SENDEMAIL)
- 2 Script
- 3 DOS function (don't shrink VBBS out of memory)
- 4 DOS function (shrink VBBS out of memory)
- 5 Transfer control to a different function block
-
- A sample function block to handle E-mail might look some-
- thing like this (without the parts inside angle-brackets):
-
- EMAIL <name of menu file>
- <no database attached; E-mail's automatic>
- e 001 1 sendemail
- m 001 1 reademailto
- f 001 1 feedback
- s 001 1 reademailsent
- q 000 5 start <on quitting, return to START.FB>
-
- VBBS 6.12 Documentation -- 7-7
-
-
- The Default START.FB
- ────────────────────
-
- VBBS could easily have been distributed with a blank menu;
- instead, a default START.FB is included which reflects the con-
- figuration of the software on the author's BBS, "Virtual Techno-
- logies". Note the columnation at the beginning of each line and
- the topic-area designator on the second line. Other points of
- interest include: 1) the 255 SL required to transfer control to
- the SYSOP.FB function block; 2) the VBBS-AUX commands that shrink
- the BBS out of memory to execute the associated program; and 3)
- the nonalphabetic characters used as hot-keys.
-
- MAIN
- A
- $ 001 1 choosetopic
- > 001 1 nextbase
- < 001 1 prevbase
- c 001 1 selectbase
- j 001 1 setquickscan
- s 001 1 scanmsg
- n 001 1 readnewmsg
- r 001 1 readseqmsg
- p 001 1 post
- e 001 1 sendemail
- y 001 1 reademailfrom
- m 001 1 reademailto
- q 001 1 quickmail
- f 001 1 feedback
- o 001 1 door
- z 001 4 vbbs-aux %1 telecon
- d 001 1 account
- l 001 1 pagesysop
- t 001 5 files
- b 001 4 vbbs-aux %1 textfiles
- k 001 1 listcallers
- u 001 4 vbbs-aux %1 listusers
- a 001 1 autopost
- v 001 4 vbbs-aux %1 vote
- i 001 1 sysinfo
- w 001 1 who
- x 001 4 vbbs-aux %1 listnet
- * 255 5 sysop
- g 000 1 logoffyn
-
- Making changes is as simple as pulling the START.FB file
- into a text editor (even the VBBS FSE, from WITHIN the board!)
- and adding in the desired function(s). For example, you might
- add in the following line to invoke a script that shows a user
- his/her credit total:
-
- # 001 2 crcheck
-
- Notice that all this is presented in lower-case; function blocks
- are NOT case-sensitive, so the number of commands you may have
-
- VBBS 6.12 Documentation -- 7-8
-
-
- is limited to 26 letters + 10 digits + however many punctuation
- and nonalphabetic characters you can come up with (of course, if
- any FB ever gets that big, you'll probably want to split it into
- smaller chunks anyway).
-
- ╔═╗ If you start breaking your function blocks into smaller
- ╚═╝ pieces, it's important to choose letter commands -- "hot
- keys" -- in such a way that commands will be consistent
- across menus. For example, if you have the [M] key set
- to jump to the Message Menu in one function block, try
- to make it do the same thing in ALL function blocks.
- This may not be easy, but your users will appreciate not
- having to learn a different set of hotkeys at each menu.
-
-
- The Default FILES.FB and SYSOP.FB
- ─────────────────────────────────
-
- There are two other default function blocks: FILES.FB,
- which governs the file transfer section(s), and SYSOP.FB, which
- contains the commands for the sysop function block. These func-
- tion blocks are shown below:
-
- FILE1 SYSOP1
- F
- g 000 1 logoffyn m 255 1 readallemail
- m 001 1 dlmasterlist e 255 1 editfile
- u 001 1 remoteupload u 255 1 useredit
- d 001 1 downloadfile s 255 4 vbbs-aux %1 security
- r 001 1 reviewfile v 255 1 validate
- c 001 1 selectbase c 255 1 cleanup
- j 001 1 setnewfilesscan q 000 5 start
- l 001 1 listfiles
- n 001 1 newfiles
- s 001 1 searchall
- b 001 1 batchdl
- f 001 1 findfiles
- > 001 1 nextbase
- < 001 1 prevbase
- p 001 1 topdownloads
- y 001 1 ratio
- z 255 1 sysopupload
- x 255 1 reviewuploads
- q 000 5 start
-
-
- One change to FILES.FB you might want to try right off the bat
- -- if you have more than one files area and want to fiddle with
- the function blocks (and if Roland hasn't added it in as a de-
- fault command yet) -- is to add in this line:
-
- $ 001 1 choosetopic
-
- No compilation is necessary ... just save it, and the the [$]
- command to move between files topic areas is enabled, just like
-
- VBBS 6.12 Documentation -- 7-9
-
-
- in the message bases! Make sure, though, that you add the com-
- mand in your menus so your users can take advantage of it.
-
- Rearranging the commands in function blocks isn't that
- difficult -- it's just a matter of making sure you don't leave
- out any commands. For example, I have separate function blocks
- for the Main Menu (12 whole commands!), E-mail, transfers, and
- subsystems, coupled with the ability to jump between FBs with
- one keystroke. Of course, my menu structure is quite different
- from the default setup -- but that's the beauty of VBBS. It
- didn't blink an eye when I installed the changes!
- One caveat, however: your main function block MUST be
- called START.FB. It is the function block that takes over when
- the START.V script finishes running.
-
-
- Scripts and Mods
- ════════════════
-
- As stated earlier, the term "scripts" refers to programs
- written using VSCRIPT and compiled using the program VCOM.EXE;
- "mods" refers to source-code modifications (just a reminder).
-
- The VSCRIPT language is one of the most powerful features
- of VBBS (if not THE most powerful). It's a small programming
- language, somewhat similar to the REXX script language, that
- incorporates many of VBBS' functions into single command state-
- ments (with or without command-line arguments). All it takes
- is your favorite ASCII text editor or word processor and some
- familiarity with the VSCRIPT language (that's a separate part
- of the documentation; see Chapter 10 for details), and you can
- be customizing your BBS via scripts in no time.
- As an example, let's take the script mentioned earlier
- that allows users to check their credits. It consists of only
- three lines:
-
- tr
- tr "You currently have " $credits " credits."
- tr
-
- Save this file in your \V or \VSCRIPT directory (as you have it
- configured in VCONFIG) under the name CRCHECK.V (to maximize
- efficiency, you might want to keep a copy of VCOM.EXE in this
- directory as well). Compile the script:
-
- VCOM CRCHECK.V
-
- and you will see two NEW files in the directory: CRCHECK.COD
- and CRCHECK.LIT. These are the files VBBS will look for when
- you execute the script from the function block in which it's
- placed.
- There are literally dozens, if not hundreds, of VSCRIPT-
- based applications available through VirtualNET (more about that
- later). Some enterprising programmers have created casino games,
- alternate mail and voting routines, scripts to welcome new users
-
- VBBS 6.12 Documentation -- 7-10
-
-
- and take them on a tour of the BBS, show user information ...
- it's difficult to describe the variety of scripts that have been
- written by sysops and users alike!
-
- VBBS may also be modified through direct changes to the
- source code, a process known as "source modding" or simply "mod-
- ding". This DOES require that you have a copy of either Micro-
- soft's QuickBASIC compiler (version 4.5 or later). The "QBASIC"
- that comes with MS-DOS is NOT sufficient for this purpose.
-
- VBBS employs a mixed programming environment using assem-
- bly-language routines for fast COM port and program I/O, while
- using QuickBASIC as an affordable and easy-to-modify environment.
- This is in sharp contrast to many other BBS softwares, which re-
- quire a knowledge of Pascal or C and their associated compilers.
- It should be noted here, however, that in order to keep the
- source-code files from being too large, there are very few com-
- ments in the default program; this can make for an -- <ahem!> --
- INTERESTING time when you're looking for a particular routine or
- section of the code. Just thought we'd let you know in ad-
- vance ...! :-)
-
- ╔═╗ Some helpful hints to make your source modding easier:
- ╚═╝
- 1) Make backup copies of the existing source code. It
- might save you truckloads of grief later.
- 2) Print out the source code (make a pot of coffee or
- something while you do ... it takes a while) and read
- through it BEFORE you start modding. The files are
- simply too complex to try to keep up with on a screen-
- by-screen basis. Highlighting's much easier, too; my
- source-code printout has so much red ink on it that it
- looks like a bad high-school English paper.
- 3) Make sure you're thoroughly familiar with the functions
- and commands of VBBS; this will make it easier to spot
- their associated source routines.
-
- --> IMPORTANT NOTE: Access to the QB4.5 DOS source code is
- governed by a specific licensing agreement.
- You may not possess any portion of the source
- without having obtained a license to do so
- from the VBBS author, and in no case shall
- more than 100 lines of VBBS code be con-
- tained within a published modification at
- any time.
-
- ▒▒ OS/2 Version : Please note that source code is not made
- available for source modding. Full scripting
- is possible.
-
- VBBS 6.12 Documentation -- 7-11
-
-
- Scripts and Mods on VirtualNET
- ──────────────────────────────
-
- Once your BBS is a VirtualNET node (more on that in a
- bit), there are many message subs dedicated to VBBS scripts
- and mods. Two main subs are:
-
- VBBS Script Technical Support
- VBBS Source Technical Support
-
- The "VBBS Script Technical Support" sub is for the discus-
- sion of scripts and mods -- questions, troubleshooting, and the
- like. The "Virtual ModNET" is EXCLUSIVELY for the posting of
- script/mod code -- no discussion.
-
- System Taglines
- ═══════════════
-
- Many sysops whose BBSs are part of VirtualNET like to
- "personalize" posts originating from their system by adding a
- system tagline to the posts.
- System taglines are optional; if they are used, however,
- they must follow several guidelines:
-
- 1) They must include the name of the BBS, its geo-
- graphic location, VirtualNET node number, and
- version of VBBS being used;
- 2) They must be 3 lines or less AND 300 bytes or
- less (i.e., a 3-line, 350-byte tagline is NOT
- acceptable);
- 3) They must be colorized using ONLY heart-code
- ANSI (no "raw" ANSI allowed).
-
- Creating a system tagline is similar to creating a new
- menu; you make and save an ASCII version of the tagline, then
- bring it into the VBBS FSE to colorize it with heart codes.
- Since any experimental color changes are also saved with the
- tagline, it's usually a good idea to use your ASCII text edi-
- tor to delete any unnecessary color changes after you've got
- your tagline looking the way you want it.
- Taglines reside in your \TXT directory under the name(s)
- TAGLINE.xxx, where "xxx" is a number from 1 to 999. It should
- be noted that single- or double-digit extensions to these files
- should be just that, i.e., TAGLINE.1 or TAGLINE.22, and not
- TAGLINE.001 or TAGLINE.022.
-
- ╔═╗ A word or two on system taglines: they should be as dis-
- ╚═╝ tinctive as possible without being gaudy or distracting
- from the body of the message. "Eyesore" taglines are
- sometimes the butt of jokes on VirtualNET. In addition,
- some sysops try to cram every bit of information they
-
- VBBS 6.12 Documentation -- 7-12
-
-
- can about their systems into their taglines; this is
- frequently viewed as being distracting, and in general,
- a "less-is-more" approach is best advised. If you want
- to advertise your huge file base or the 42 game doors
- your system currently has, it's usually better to make
- a BBS ad for the "BBS Advertisements" sub instead
- of trying to cram this information into your tagline.
-
-
- R.I.P. Remote Imaging Protocol GUI Interface
- ════════════════════════════════════════════
-
- VBBS is now compatible with R.I.P. graphic standards.
- RipTerm is an optional mouse-driven terminal program which
- interfaces with VBBS. R.I.P. supports user's-end VGA graphics
- (sorry, no VGA locally -- the "overhead" local VGA would intro-
- duce would be of truly epic proportions) and is icon-driven. As
- of this writing, a number of communication programs now
- support R.I.P. graphics.
- Details on R.I.P.may be found in the documentation that ac-
- companies the RipTerm Program. Adding R.I.P screens is yet
- another way you can customize your VBBS installation, and the
- early reviews are enthusiastic, to say the least!
-
- As you can see, there are quite a few ways you can cus-
- tomize your VBBS to get exactly the "look-and-feel" you want.
- It's pretty much a case of you being limited only by your imagi-
- nation. You can make the graphics, menus, and command structure
- as simple or complex as you want them. Just keep in mind that
- when you make changes to your user interface, it should be to
- make your users' lives easier, NOT to push everything to the
- max for the sake of doing it.
-
-